home *** CD-ROM | disk | FTP | other *** search
/ Chip 2007 January, February, March & April / Chip-Cover-CD-2007-02.iso / Pakiet bezpieczenstwa / mini Pentoo LiveCD 2006.1 / mpentoo-2006.1.iso / livecd.squashfs / usr / lib / mozilla-firefox / include / dom / nsIScriptContext.h < prev    next >
C/C++ Source or Header  |  2006-05-08  |  15KB  |  378 lines
  1. /* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
  2. /* ***** BEGIN LICENSE BLOCK *****
  3.  * Version: MPL 1.1/GPL 2.0/LGPL 2.1
  4.  *
  5.  * The contents of this file are subject to the Mozilla Public License Version
  6.  * 1.1 (the "License"); you may not use this file except in compliance with
  7.  * the License. You may obtain a copy of the License at
  8.  * http://www.mozilla.org/MPL/
  9.  *
  10.  * Software distributed under the License is distributed on an "AS IS" basis,
  11.  * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
  12.  * for the specific language governing rights and limitations under the
  13.  * License.
  14.  *
  15.  * The Original Code is mozilla.org code.
  16.  *
  17.  * The Initial Developer of the Original Code is
  18.  * Netscape Communications Corporation.
  19.  * Portions created by the Initial Developer are Copyright (C) 1998-1999
  20.  * the Initial Developer. All Rights Reserved.
  21.  *
  22.  * Contributor(s):
  23.  *
  24.  * Alternatively, the contents of this file may be used under the terms of
  25.  * either of the GNU General Public License Version 2 or later (the "GPL"),
  26.  * or the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
  27.  * in which case the provisions of the GPL or the LGPL are applicable instead
  28.  * of those above. If you wish to allow use of your version of this file only
  29.  * under the terms of either the GPL or the LGPL, and not to allow others to
  30.  * use your version of this file under the terms of the MPL, indicate your
  31.  * decision by deleting the provisions above and replace them with the notice
  32.  * and other provisions required by the GPL or the LGPL. If you do not delete
  33.  * the provisions above, a recipient may use your version of this file under
  34.  * the terms of any one of the MPL, the GPL or the LGPL.
  35.  *
  36.  * ***** END LICENSE BLOCK ***** */
  37.  
  38. #ifndef nsIScriptContext_h__
  39. #define nsIScriptContext_h__
  40.  
  41. #include "nscore.h"
  42. #include "nsString.h"
  43. #include "nsISupports.h"
  44. #include "nsCOMPtr.h"
  45. #include "jsapi.h"
  46.  
  47. class nsIScriptGlobalObject;
  48. class nsIScriptSecurityManager;
  49. class nsIScriptContextOwner;
  50. class nsIPrincipal;
  51. class nsIAtom;
  52.  
  53. typedef void (*nsScriptTerminationFunc)(nsISupports* aRef);
  54.  
  55. #define NS_ISCRIPTCONTEXT_IID \
  56. { /* b3fd8821-b46d-4160-913f-cc8fe8176f5f */ \
  57.   0xb3fd8821, 0xb46d, 0x4160, \
  58.   {0x91, 0x3f, 0xcc, 0x8f, 0xe8, 0x17, 0x6f, 0x5f} }
  59.  
  60. /**
  61.  * It is used by the application to initialize a runtime and run scripts.
  62.  * A script runtime would implement this interface.
  63.  * <P><I>It does have a bit too much java script information now, that
  64.  * should be removed in a short time. Ideally this interface will be
  65.  * language neutral</I>
  66.  */
  67. class nsIScriptContext : public nsISupports
  68. {
  69. public:
  70.   NS_DEFINE_STATIC_IID_ACCESSOR(NS_ISCRIPTCONTEXT_IID)
  71.  
  72.   /**
  73.    * Compile and execute a script.
  74.    *
  75.    * @param aScript a string representing the script to be executed
  76.    * @param aScopeObject a JavaScript JSObject for the scope to execute in, or
  77.    *                     nsnull to use a default scope
  78.    * @param aPrincipal the principal that produced the script
  79.    * @param aURL the URL or filename for error messages
  80.    * @param aLineNo the starting line number of the script for error messages
  81.    * @param aVersion the script language version to use when executing
  82.    * @param aRetValue the result of executing the script, or null for no result.
  83.    *        If this is a JS context, it's the caller's responsibility to
  84.    *        preserve aRetValue from GC across this call
  85.    * @param aIsUndefined true if the result of executing the script is the
  86.    *                     undefined value
  87.    *
  88.    * @return NS_OK if the script was valid and got executed
  89.    *
  90.    **/
  91.   virtual nsresult EvaluateString(const nsAString& aScript,
  92.                                   void *aScopeObject,
  93.                                   nsIPrincipal *aPrincipal,
  94.                                   const char *aURL,
  95.                                   PRUint32 aLineNo,
  96.                                   const char* aVersion,
  97.                                   nsAString *aRetValue,
  98.                                   PRBool* aIsUndefined) = 0;
  99.  
  100.   virtual nsresult EvaluateStringWithValue(const nsAString& aScript,
  101.                                            void *aScopeObject,
  102.                                            nsIPrincipal *aPrincipal,
  103.                                            const char *aURL,
  104.                                            PRUint32 aLineNo,
  105.                                            const char* aVersion,
  106.                                            void* aRetValue,
  107.                                            PRBool* aIsUndefined) = 0;
  108.  
  109.   /**
  110.    * Compile a script.
  111.    *
  112.    * @param aText a PRUnichar buffer containing script source
  113.    * @param aTextLength number of characters in aText
  114.    * @param aScopeObject an object telling the scope in which to execute,
  115.    *                     or nsnull to use a default scope
  116.    * @param aPrincipal the principal that produced the script
  117.    * @param aURL the URL or filename for error messages
  118.    * @param aLineNo the starting line number of the script for error messages
  119.    * @param aVersion the script language version to use when executing
  120.    * @param aScriptObject an executable object that's the result of compiling
  121.    *                      the script.  The caller is responsible for GC rooting
  122.    *                      this object.
  123.    *
  124.    * @return NS_OK if the script source was valid and got compiled
  125.    *
  126.    **/
  127.   virtual nsresult CompileScript(const PRUnichar* aText,
  128.                                  PRInt32 aTextLength,
  129.                                  void* aScopeObject,
  130.                                  nsIPrincipal* aPrincipal,
  131.                                  const char* aURL,
  132.                                  PRUint32 aLineNo,
  133.                                  const char* aVersion,
  134.                                  void** aScriptObject) = 0;
  135.  
  136.   /**
  137.    * Execute a precompiled script object.
  138.    *
  139.    * @param aScriptObject an object representing the script to be executed
  140.    * @param aScopeObject an object telling the scope in which to execute,
  141.    *                     or nsnull to use a default scope
  142.    * @param aRetValue the result of executing the script, may be null in
  143.    *                  which case no result string is computed
  144.    * @param aIsUndefined true if the result of executing the script is the
  145.    *                     undefined value, may be null for "don't care"
  146.    *
  147.    * @return NS_OK if the script was valid and got executed
  148.    *
  149.    */
  150.   virtual nsresult ExecuteScript(void* aScriptObject,
  151.                                  void* aScopeObject,
  152.                                  nsAString* aRetValue,
  153.                                  PRBool* aIsUndefined) = 0;
  154.  
  155.   /**
  156.    * Compile the event handler named by atom aName, with function body aBody
  157.    * into a function object returned if ok via *aHandler.  Bind the lowercase
  158.    * ASCII name to the function in its parent object aTarget.
  159.    *
  160.    * @param aTarget an object telling the scope in which to bind the compiled
  161.    *        event handler function to aName.
  162.    * @param aName an nsIAtom pointer naming the function; it must be lowercase
  163.    *        and ASCII, and should not be longer than 63 chars.  This bound on
  164.    *        length is enforced only by assertions, so caveat caller!
  165.    * @param aEventName the name that the event object should be bound to
  166.    * @param aBody the event handler function's body
  167.    * @param aURL the URL or filename for error messages
  168.    * @param aLineNo the starting line number of the script for error messages
  169.    * @param aShared flag telling whether the compiled event handler will be
  170.    *        shared via nsIScriptEventHandlerOwner, in which case any static
  171.    *        link compiled into it based on aTarget should be cleared, both
  172.    *        to avoid entraining garbage to be collected, and to trigger static
  173.    *        link re-binding in BindCompiledEventHandler (see below).
  174.    * @param aHandler the out parameter in which a void pointer to the compiled
  175.    *        function object is returned on success; may be null, meaning the
  176.    *        caller doesn't need to store the handler for later use.
  177.    *
  178.    * @return NS_OK if the function body was valid and got compiled
  179.    */
  180.   virtual nsresult CompileEventHandler(void* aTarget,
  181.                                        nsIAtom* aName,
  182.                                        const char* aEventName,
  183.                                        const nsAString& aBody,
  184.                                        const char* aURL,
  185.                                        PRUint32 aLineNo,
  186.                                        PRBool aShared,
  187.                                        void** aHandler) = 0;
  188.  
  189.   /**
  190.    * Call the function object with given args and return its boolean result,
  191.    * or true if the result isn't boolean.
  192.    *
  193.    * @param aTarget an object telling the scope in which to bind the compiled
  194.    *        event handler function.
  195.    * @param aHandler function object (function and static scope) to invoke.
  196.    * @param argc actual argument count; length of argv
  197.    * @param argv vector of arguments; length is argc
  198.    * @param aBoolResult out parameter returning boolean function result, or
  199.    *        true if the result was not boolean.
  200.    **/
  201.   virtual nsresult CallEventHandler(JSObject* aTarget, JSObject* aHandler,
  202.                                     uintN argc, jsval* argv,
  203.                                     jsval* rval) = 0;
  204.  
  205.   /**
  206.    * Bind an already-compiled event handler function to a name in the given
  207.    * scope object.  The same restrictions on aName (lowercase ASCII, not too
  208.    * long) applies here as for CompileEventHandler.  Scripting languages with
  209.    * static scoping must re-bind the scope chain for aHandler to begin (after
  210.    * the activation scope for aHandler itself, typically) with aTarget's scope.
  211.    *
  212.    * @param aTarget an object telling the scope in which to bind the compiled
  213.    *        event handler function.
  214.    * @param aName an nsIAtom pointer naming the function; it must be lowercase
  215.    *        and ASCII, and should not be longer than 63 chars.  This bound on
  216.    *        length is enforced only by assertions, so caveat caller!
  217.    * @param aHandler the function object to name, created by an earlier call to
  218.    *        CompileEventHandler
  219.    * @return NS_OK if the function was successfully bound to the name
  220.    */
  221.   virtual nsresult BindCompiledEventHandler(void* aTarget,
  222.                                             nsIAtom* aName,
  223.                                             void* aHandler) = 0;
  224.  
  225.   virtual nsresult CompileFunction(void* aTarget,
  226.                                    const nsACString& aName,
  227.                                    PRUint32 aArgCount,
  228.                                    const char** aArgArray,
  229.                                    const nsAString& aBody,
  230.                                    const char* aURL,
  231.                                    PRUint32 aLineNo,
  232.                                    PRBool aShared,
  233.                                    void** aFunctionObject) = 0;
  234.  
  235.  
  236.   /**
  237.    * Set the default scripting language version for this context, which must
  238.    * be a context specific to a particular scripting language.
  239.    *
  240.    **/
  241.   virtual void SetDefaultLanguageVersion(const char* aVersion) = 0;
  242.  
  243.   /**
  244.    * Return the global object.
  245.    *
  246.    **/
  247.   virtual nsIScriptGlobalObject *GetGlobalObject() = 0;
  248.  
  249.   /**
  250.    * Return the native script context
  251.    *
  252.    **/
  253.   virtual void *GetNativeContext() = 0;
  254.  
  255.   /**
  256.    * Init this context.
  257.    *
  258.    * @param aGlobalObject the gobal object
  259.    *
  260.    * @return NS_OK if context initialization was successful
  261.    *
  262.    **/
  263.   virtual nsresult InitContext(nsIScriptGlobalObject *aGlobalObject) = 0;
  264.  
  265.   /**
  266.    * Check to see if context is as yet intialized. Used to prevent
  267.    * reentrancy issues during the initialization process.
  268.    *
  269.    * @return PR_TRUE if initialized, PR_FALSE if not
  270.    *
  271.    */
  272.   virtual PRBool IsContextInitialized() = 0;
  273.  
  274.   /**
  275.    * For garbage collected systems, do a synchronous collection pass.
  276.    * May be a no-op on other systems
  277.    *
  278.    * @return NS_OK if the method is successful
  279.    */
  280.   virtual void GC() = 0;
  281.  
  282.   /**
  283.    * Inform the context that a script was evaluated.
  284.    * A GC may be done if "necessary."
  285.    * This call is necessary if script evaluation is done
  286.    * without using the EvaluateScript method.
  287.    * @param aTerminated If true then call termination function if it was 
  288.    *    previously set. Within DOM this will always be true, but outside 
  289.    *    callers (such as xpconnect) who may do script evaluations nested
  290.    *    inside DOM script evaluations can pass false to avoid premature
  291.    *    calls to the termination function.
  292.    * @return NS_OK if the method is successful
  293.    */
  294.   virtual void ScriptEvaluated(PRBool aTerminated) = 0;
  295.  
  296.   /**
  297.    * Let the script context know who its owner is.
  298.    * The script context should not addref the owner. It
  299.    * will be told when the owner goes away.
  300.    * @return NS_OK if the method is successful
  301.    */
  302.   virtual void SetOwner(nsIScriptContextOwner* owner) = 0;
  303.  
  304.   /**
  305.    * Get the script context of the owner. The method
  306.    * addrefs the returned reference according to regular
  307.    * XPCOM rules, even though the internal reference itself
  308.    * is a "weak" reference.
  309.    */
  310.   virtual nsIScriptContextOwner *GetOwner() = 0;
  311.  
  312.   /**
  313.    * Called to specify a function that should be called when the current
  314.    * script (if there is one) terminates. Generally used if breakdown
  315.    * of script state needs to happen, but should be deferred till
  316.    * the end of script evaluation.
  317.    *
  318.    * @throws NS_ERROR_OUT_OF_MEMORY if that happens
  319.    */
  320.   virtual nsresult SetTerminationFunction(nsScriptTerminationFunc aFunc,
  321.                                           nsISupports* aRef) = 0;
  322.  
  323.   /**
  324.    * Called to disable/enable script execution in this context.
  325.    */
  326.   virtual PRBool GetScriptsEnabled() = 0;
  327.   virtual void SetScriptsEnabled(PRBool aEnabled, PRBool aFireTimeouts) = 0;
  328.  
  329.   /** 
  330.    * Called to set/get information if the script context is
  331.    * currently processing a script tag
  332.    */
  333.   virtual PRBool GetProcessingScriptTag() = 0;
  334.   virtual void SetProcessingScriptTag(PRBool aResult) = 0;
  335.  
  336.   /**
  337.    * Tell the context whether or not to GC when destroyed.
  338.    */
  339.   virtual void SetGCOnDestruction(PRBool aGCOnDestruction) = 0;
  340.  
  341.   /**
  342.    * Initialize DOM classes on aGlobalObj, always call
  343.    * WillInitializeContext() before calling InitContext(), and always
  344.    * call DidInitializeContext() when a context is fully
  345.    * (successfully) initialized.
  346.    */
  347.   virtual nsresult InitClasses(JSObject *aGlobalObj) = 0;
  348.  
  349.   /**
  350.    * Tell the context we're about to be reinitialize it.
  351.    */
  352.   virtual void WillInitializeContext() = 0;
  353.  
  354.   /**
  355.    * Dell the context we're done reinitializing it.
  356.    */
  357.   virtual void DidInitializeContext() = 0;
  358. };
  359.  
  360. inline nsIScriptContext *
  361. GetScriptContextFromJSContext(JSContext *cx)
  362. {
  363.   if (!(::JS_GetOptions(cx) & JSOPTION_PRIVATE_IS_NSISUPPORTS)) {
  364.     return nsnull;
  365.   }
  366.  
  367.   nsCOMPtr<nsIScriptContext> scx =
  368.     do_QueryInterface(NS_STATIC_CAST(nsISupports *,
  369.                                      ::JS_GetContextPrivate(cx)));
  370.  
  371.   // This will return a pointer to something that's about to be
  372.   // released, but that's ok here.
  373.   return scx;
  374. }
  375.  
  376. #endif // nsIScriptContext_h__
  377.  
  378.